home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1997 October / macformat-055.iso / mac / Shareware Plus / Developers / Caveman Sound System / CMSoundSystem.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-06-16  |  18.8 KB  |  461 lines  |  [TEXT/ALFA]
  1. /*****************************************************************************
  2.  * FILE:        CMSoundSystem.h
  3.  * AUTHOR:        David Hay
  4.  * CREATED:        March 9, 1995
  5.  * DESCRIPTION:    Interface to the Caveman Sound System.
  6.  *    
  7.  * Copyright © 1995-1997 David Hay
  8.  *
  9.  * Permission to use, copy, and distribute this software and its documentation
  10.  * for any purpose is hereby granted without fee,  provided that (i) the above
  11.  * copyright notices  and  this permission notice  appear in all copies of the
  12.  * software  and  related documentation,  and (ii) the names of David Hay  and
  13.  * Caveman Creations may not be used in any advertising or publicity  relating
  14.  * to the software without the specific, prior written permission of David Hay
  15.  *
  16.  * THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
  17.  * IMPLIED  OR  OTHERWISE,  INCLUDING,  WITHOUT  LIMITATION,  ANY WARRANTY  OF
  18.  * MERCHANTABILITY  OR  FITNESS FOR  A PARTICULAR PURPOSE.  IN NO EVENT  SHALL
  19.  * DAVID HAY  OR  CAVEMAN CREATIONS  BE LIABLE  FOR  ANY SPECIAL,  INCIDENTAL,
  20.  * INDIRECT  OR  CONSEQUENTIAL DAMAGES OF ANY KIND,  OR ANY DAMAGES WHATSOEVER
  21.  * RESULTING FROM LOSS OF USE, DATA OR PROFITS,  WHETHER OR NOT ADVISED OF THE
  22.  * POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN
  23.  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  24.  *
  25.  *
  26.  * Version History:
  27.  *
  28.  * 1.0 (09/11/95)
  29.  *        - Initial release
  30.  *
  31.  * 1.1 (03/05/96)
  32.  *        - Incorporated changes by Dario Accornero (dappsoft@mix.it)  Thanks
  33.  *          Dario for all your work! (look for "// DA on 01/20/96")
  34.  *            • added PPC support in the callback routine
  35.  *            • added stero Macs support in the channel allocation routines
  36.  *            • added double buffer support in order to speed up sound output
  37.  *              on all Macs
  38.  *            • chaned SoundSystem allocation, in order to lower global vars
  39.  *              space memory charge; now, the SoundSystem is accessed thru a
  40.  *              pointer, so it is *necessare* to allocate the system before
  41.  *              using it, otherwise the code will crash…
  42.  *            • added priorities support
  43.  *            • added channel volume control (get/set)
  44.  *            • CodeWarrior is now supported
  45.  *        - Cleaned up the code a bit.
  46.  *        - Added some internal routines for code that was getting repeated by
  47.  *          both sound and music routines.
  48.  *****************************************************************************/
  49.  
  50. #ifndef __CMSOUNDSYSTEM__
  51. #define __CMSOUNDSYSTEM__
  52.  
  53. #ifndef __SOUND__
  54. #include <Sound.h>
  55. #endif
  56.  
  57. #define kMaxChannels      20    /* The maximum number of channels allowed */
  58. #define kMaxSounds          50    /* Maximum number of sounds that may be registered */
  59. #define kMaxMusicLen      128    /* Maximum length of a song sequence. */
  60. #define kNoSound          (-1)    /* Reference number for no sound at all */
  61. #define kSoundResource      (-2)    /* Reference number of an unregistered sound */
  62. #define kNoLoop              (-1)    /* In a music sequence, indicates no looping */
  63. #define kMusicResType      'MUSL'/* Resource type for a music list */
  64. #define kAsynchronous      true    /* Constant to define asychronous play */
  65. #define kPriorityOverride 1        /* Error code returned when a sound is overridden */
  66. #define kPriorityDenied   2        /* Error code returned when no channels are free */
  67.  
  68. // DA on 01/20/96: constants used to get and set output volume on a specific channel
  69.  
  70. #define    kMinVolume        0        /* minimum volume level */
  71. #define    kMaxVolume        256        /* maximum volume level */
  72.  
  73. /*****************************************************************************
  74. ** PlaySequence        -- Describes a sequence of sounds to play in order to
  75. **                       produce a piece of music.
  76. **
  77. **        loopStart        - the position in the sequence to jump to after the
  78. **                          sequence as finished.
  79. **        sequenceLength    - the number of sounds to play in the sequence.
  80. **        sequence[]        - the list of sounds to play. This array determines
  81. **                          the order of sounds to play, allowing a sound
  82. **                          to be repeated several times in a piece of music.
  83. **/
  84.  
  85. typedef struct PlaySequence
  86. {
  87.     short    loopStart;
  88.     short    sequenceLength;
  89.     short    sequence[1];        /* Variable sized */
  90. } PlaySequence, *PlaySequencePtr, **PlaySequenceHandle;
  91.  
  92.  
  93. /*----------------------- INITIALIZATION/DEALLOCATION -----------------------*/
  94.  
  95. extern OSErr
  96. CMSInitSound( short numChannels );
  97. /*
  98.  *    Initialize the sound system.
  99.  *
  100.  *    ON ENTRY:    'numChannels' is a number greater than 0
  101.  *    ON EXIT:    The sound system has been initialized to provide 'numChannels'
  102.  *                channels of sound.
  103.  *                Any errors are returned.
  104.  *****************************************************************************/
  105.  
  106. extern void
  107. CMSDisposeSound( void );
  108. /*
  109.  *    Dispose of any registered sound and internal data used by the sound
  110.  *    system.  Any sound system functions should not be used after calling
  111.  *    this function.
  112.  *
  113.  *    ON ENTRY:    The sound system has been previously initialized
  114.  *    ON EXIT:    Any data used by the sound system is disposed of.
  115.  *****************************************************************************/
  116.  
  117.  
  118. /*---------------------------- CHANNEL MANAGEMENT ---------------------------*/
  119.  
  120. extern OSErr
  121. CMSCloseChannel( short channelNum );
  122. /*
  123.  *    Closes sound channel number 'channelNum'.  The channel is still allocated,
  124.  *    but sound may not be played through it.  To reopen the channel, call
  125.  *    CMSOpenChannel()
  126.  *
  127.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  128.  *                    available channels [as passed to CMSInitSound()]
  129.  *                The sound system has been initialized
  130.  *    ON EXIT:    The channel number 'channelNum' has been closed.
  131.  *                Any errors are returned.
  132.  *****************************************************************************/
  133.  
  134. extern OSErr
  135. CMSCloseAllChannels( void );
  136. /*
  137.  *    Closes all of the open channels.  The channels are still allocated, but
  138.  *    sound may not be played through them.  To reopen a specific channel, call
  139.  *    CMSOpenChannel().  To reopen all channels, call CMSOpenAllChannels().
  140.  *
  141.  *    ON ENTRY:    The sound system has been initialized
  142.  *    ON EXIT:    All open sound channels have been closed.
  143.  *                Any errors are returned.
  144.  *****************************************************************************/
  145.  
  146. extern OSErr
  147. CMSOpenChannel( short channelNum );
  148. /*
  149.  *    Opens channel number 'channelNum'.  After opening a channel, sound may be
  150.  *    played through that sound channel.  If the sound channel is alreay open,
  151.  *    nothing is done.
  152.  *
  153.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  154.  *                    available channels [as passed to CMSInitSound()]
  155.  *                The sound system has been initialized
  156.  *    ON EXIT:    The channel, 'channelNum' is opened and ready to play sounds
  157.  *                Any errors are returned.
  158.  *****************************************************************************/
  159.  
  160. extern OSErr
  161. CMSOpenAllChannels( void );
  162. /*
  163.  *    Opens all currently closed sound channels.  After opening a sound channel,
  164.  *    sound may be played on that sound channel.
  165.  *
  166.  *    ON ENTRY:    The sound system has been initialized.
  167.  *    ON EXIT:    All allocated sound channels have been opened.
  168.  *                Any errors are returned.
  169.  *****************************************************************************/
  170.  
  171. extern OSErr
  172. CMSStopSound( short channelNum );
  173. /*
  174.  *    Stops any currently playing sounds on sound channel 'channelNum'
  175.  *
  176.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  177.  *                    available sound channels [as passed to CMSInitSound()]
  178.  *    ON EXIT:    Any sounds playing on channel, 'channelNum' are stopped. If
  179.  *                the sound playing on the sound channel was a sound resource,
  180.  *                the resource is unlocked so that it may be purged.
  181.  *****************************************************************************/
  182.  
  183. extern void
  184. CMSIdleSoundTask( void );
  185. /*
  186.  *    Handles any housecleaning tasks the sound system may need to perform. It
  187.  *    should be called before playing a sound resource.
  188.  *
  189.  *    ON ENTRY:    The sound system has been initialized
  190.  *    ON EXIT:    Any routine chores the sound system have been performed.
  191.  *****************************************************************************/
  192.  
  193. extern OSErr
  194. CMSGetSoundPlaying( short channelNum, short* refNum );
  195. /*
  196.  *    Get the reference number of the sound currently playing on a sound channel.
  197.  *
  198.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  199.  *                    available sound channels [as passed to CMSInitSound()]
  200.  *                'refNum' points to location to store the currently playing
  201.  *                    sound reference number.
  202.  *    ON EXIT:    The sound playing on the channel, 'channelNum' is returned in
  203.  *                the area pointed to by 'refNum'.  If no sounds are currently
  204.  *                playing, 'kNoSound' is returned in 'refNum'.  If the currently
  205.  *                playing sound is a sound resource, 'kSoundResource' is returned
  206.  *****************************************************************************/
  207.  
  208. extern OSErr
  209. CMSWaitForSilence( short channelNum );
  210. /*
  211.  *    Wait for a sound channel to fall silent.  This should not be called on
  212.  *    a sound channel that is playing music with a loop as it will never return.
  213.  *
  214.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  215.  *                    available sound channels [as passed to CMSInitSound()]
  216.  *                    that is not playing music with a loop.
  217.  *    ON EXIT:    The channel, 'channelNum' has fallen silent and is no longer
  218.  *                producing sound.
  219.  *                Any errors are returned.
  220.  *****************************************************************************/
  221.  
  222.  
  223. /*--------------------------- SOUND DATA MANAGEMENT -------------------------*/
  224.  
  225. extern OSErr
  226. CMSRegisterSound( SndListHandle theSound, short* refNum );
  227. /*
  228.  *    Registers a sound with the sound system for later playback.
  229.  *
  230.  *    ON ENTRY:    'theSound' is a valid sound handle.
  231.  *                'refNum' points to space to store a sound reference number.
  232.  *    ON EXIT:    The sound handle 'theSound' has been registered with the
  233.  *                sound system.  The sound may be played back at a later time
  234.  *                by calling CMSPlaySound() with the returned reference number.
  235.  *                Any errors are returned.
  236.  *****************************************************************************/
  237.  
  238. extern OSErr
  239. CMSRemoveSound( short refNum );
  240. /*
  241.  *    Removes a previously registered sound from the sound system.
  242.  *
  243.  *    ON ENTRY:    'refNum' is the reference number of a sound previously
  244.  *                    registered with the sound system with either
  245.  *                    CMSRegisterSound() or CMSLoadSound().
  246.  *    ON EXIT:    The sound referenced by 'refNum' is removed from the sound
  247.  *                system and disposed of.
  248.  *                Any errors are returned.
  249.  *****************************************************************************/
  250.  
  251. extern OSErr
  252. CMSLoadSound( short soundID, short* refNum );
  253. /*
  254.  *    Loads a sound from the current resource file and registers it with the
  255.  *    sound system.
  256.  *
  257.  *    ON ENTRY:    'soundID' is the resource ID of a valid 'snd ' resource.
  258.  *                'refNum' points to space to store a sound reference number.
  259.  *    ON EXIT:    The sound resource ('snd ') number 'soundID' is loaded from
  260.  *                the current resource file and registered with the sound
  261.  *                system.
  262.  *                Any error codes are returned.
  263.  *****************************************************************************/
  264.  
  265. extern OSErr
  266. CMSPlaySound( short refNum, short channelNum );
  267. /*
  268.  *    Plays a registered sound on a sound channel.
  269.  *
  270.  *    ON ENTRY:    'refNum' is the reference number of a sound previously
  271.  *                    registered with the sound system with either
  272.  *                    CMSRegisterSound() or CMSLoadSound().
  273.  *                'channelNum' is a positive number less than the number of
  274.  *                    available sound channels [as passed to CMSInitSound()]
  275.  *    ON EXIT:    The sound referenced by 'refNum' has begun playing on sound
  276.  *                channel, 'channelNum'.
  277.  *                Any error codes are returned.
  278.  *****************************************************************************/
  279.  
  280. extern OSErr
  281. CMSPlaySoundResource( short resID, short channelNum, Boolean async );
  282. /*
  283.  *    Plays a sound from a resource file.  This function is meant to provide
  284.  *    the functionality of SndPlay() through the sound system.
  285.  *
  286.  *    ON ENTRY:    'resID' is the number of a valid 'snd ' resrouce to play
  287.  *                'channelNum' is a positive number less than the number of
  288.  *                    available sound channels [as passed to CMSInitSound()]
  289.  *                'async' is a boolean value indicating whether the sound should
  290.  *                    be played asynchronosly or not.
  291.  *    ON EXIT:    The sound resource has begun playing on channel, 'channelNum'.
  292.  *                If 'async' is false, then CMSPlaySoundResource() will not
  293.  *                return until the sound has finished playing in it's entirety.
  294.  *                Any error codes are returned.
  295.  *****************************************************************************/
  296.  
  297.  
  298. /*----------------------------- MUSIC MANAGEMENT ----------------------------*/
  299.  
  300. extern OSErr
  301. CMSLoadMusic( short musicID );
  302. /*
  303.  *    Loads the sounds and music sequence data as defined by the music list
  304.  *    resource 'musicID'.  The music may then be played with a call to
  305.  *    CMSPlayMusic().
  306.  *
  307.  *    ON ENTRY:    'musicID' is the number of a valid 'MUSL' resource to load.
  308.  *    ON EXIT:    Loads the music described by the 'MUSL' resource, 'musicID'.
  309.  *                Each of the sounds listed in the play sequence is loaded and
  310.  *                registered with the sound system. The internal play sequence
  311.  *                is set up in preparation for playing music.
  312.  *****************************************************************************/
  313.  
  314. extern OSErr
  315. CMSRemoveMusic( void );
  316. /*
  317.  *    Removes the currently loaded piece of music from the sound system.  Any
  318.  *    sounds associated with playing music are ungregistered and freed.
  319.  *
  320.  *    ON ENTRY:    The sound system has been initialized
  321.  *    ON EXIT:    A piece of music previously loaded with CMSLoadMusic() is
  322.  *                removed from the system.  Any sounds associated with the
  323.  *                music are removed from the system and freed.  If no music
  324.  *                had been previously loaded, control is returned to the caller
  325.  *                immediately with no errors.
  326.  *****************************************************************************/
  327.  
  328. extern OSErr
  329. CMSPlayMusic( short channelNum );
  330. /*
  331.  *    Begins a piece of music previously loaded with CMSLoadMusic().
  332.  *
  333.  *    ON ENTRY:    'channelNum' is a positive number less than the number of
  334.  *                    available sound channels [as passed to CMSInitSound()]
  335.  *    ON EXIT:    The music previously loaded has begun to play on sound channel
  336.  *                'channelNum'.   The music will continue until it reaches the
  337.  *                end of the piece (if there are no loops).  Or until the sound
  338.  *                on the channel is silenced with a call to CMSStopSound().
  339.  *****************************************************************************/
  340.  
  341.  
  342. /*----------------------------- UTILITY ROUTINES ----------------------------*/
  343.  
  344. extern SoundHeaderPtr
  345. CMSGetSoundHeader( SndListHandle sndHandle );
  346. /*
  347.  *    Obtains a pointer to the sound header in the given sound resource. Because
  348.  *    a pointer into the handle is returned, the handle is locked and should not
  349.  *    be unlocked until the sound header is no longer needed. A pointer to a
  350.  *    sampled sound header is returned even if the sound header is actually an
  351.  *    extended sound header or a compressed sound header.
  352.  *
  353.  *    ON ENTRY:    'sndHandle' is a valid sound handle.
  354.  *    ON EXIT:    A pointer to a valid sound header in the sound 'sndHandle' is
  355.  *                returned. If there is not a sound header in the given resource,
  356.  *                then NULL is returned.
  357.  *****************************************************************************/
  358.  
  359. extern OSErr
  360. CMSGetSoundHeaderOffset( SndListHandle soundHandle, long* theOffset );
  361. /*
  362.  *    Traverses a sound resource until it reaches the sound data.    It returns
  363.  *    the offset in bytes from the beginning of a sound resource to the sound
  364.  *    header.
  365.  *
  366.  *    ON ENTRY:    'soundHandle' is a valid sound handle.
  367.  *                'theOffset' points to a location to store the header offset.
  368.  *    ON EXIT:    The offset in the sound handle 'soundHandle' is returned in
  369.  *                the space pointed to by 'theOffset'.
  370.  *                Any errors are returned.
  371.  *****************************************************************************/
  372.  
  373.  
  374. /*----------------------------- INQUIRY ROUTINES ----------------------------*/
  375.  
  376. extern Boolean
  377. CMSHasNewSoundManager( void );
  378. /*
  379.  *    Determines if the current sound manager is the "new" one.  The "new"
  380.  *    Sound Manager contains the _SoundDispatch trap and is version 2.0 or
  381.  *    greater.
  382.  *
  383.  *    ON ENTRY:    no preconditions
  384.  *    ON EXIT:    Returns true if the "new" sound manager is present on the
  385.  *                current machine.
  386.  *****************************************************************************/
  387.  
  388. extern Boolean
  389. CMSHasMultipleChannels( void );
  390. /*
  391.  *    Determines if the currently running sound manager is capable of supporting
  392.  *    multiple channels of sound.
  393.  *
  394.  *    ON ENTRY:    no preconditions
  395.  *    ON EXIT:    Returns true if the currently running sound manager is capable
  396.  *                of supporting multiple channels of sound.
  397.  *****************************************************************************/
  398.  
  399. // DA on 01/20/96: public routines added
  400.  
  401. extern OSErr
  402. CMSGetChannelVolume( short channelNum, unsigned short *volume );
  403. /*
  404.  *    Reads the current volume on the selected channel.
  405.  *
  406.  *    ON ENTRY:    'channelNum' is a valid channel number.
  407.  *                'volume' is a pointer to an unsigned short value.
  408.  *    ON EXIT:    Returns 'noErr' if the volume was correctly read from the specified
  409.  *                channel; in this case, 'volume' contains a number between kMinVolume
  410.  *                and kMaxVolume.
  411.  *****************************************************************************/
  412.  
  413. extern OSErr
  414. CMSSetChannelVolume( short channelNum, unsigned short volume );
  415. /*
  416.  *    Assigns specified volume to a selected channel.
  417.  *
  418.  *    ON ENTRY:    'channelNum' is a valid channel number.
  419.  *                'volume' is a value between zero and 256.
  420.  *    ON EXIT:    Returns 'noErr' if the volume was correctly assigned; in this case,
  421.  *                the new volume has been assigned to the selected channel.
  422.  *****************************************************************************/
  423.  
  424. extern OSErr
  425. CMSOpenSoundTool( short numChannels );
  426. /*
  427.  *    Initialize the SoundSystem and allocate all requested channels.
  428.  *
  429.  *    ON ENTRY:    'numChannels' is the number of channels to be opened.
  430.  *    ON EXIT:    Returns 'noErr' if the package has been correctly inited.
  431.  *****************************************************************************/
  432.  
  433. extern OSErr
  434. CMSPlaySoundPriority( short sound, short priority );
  435. /*
  436.  *    Play a sound (if possible) with a specified priority on any sound channel.
  437.  *
  438.  *    ON ENTRY:    'sound' is the sound reference number to be played.
  439.  *                'priority' is the desired priority of the sound to be played.
  440.  *    ON EXIT:    Returns: 'noErr' if the sound was played on a free channel;
  441.  *                kPriorityOverride if the sound was played on a channel which
  442.  *                had lower priority; kPriorityDenied if the sound was not played
  443.  *                because all channels had a higher priority, or an error code
  444.  *                from the Sound Manager if there had been troubles with sound
  445.  *                playing.
  446.  *****************************************************************************/
  447.  
  448. extern OSErr
  449. CMSSetToolVolume( short volume );
  450. /*
  451.  *    Increment or decrement the volume on all open channels.
  452.  *
  453.  *    ON ENTRY:    'volume' is positive if the volume has be to raised; negative
  454.  *                otherwise.
  455.  *    ON EXIT:    Returns 'noErr' if the volume was successfully changed on all
  456.  *                open channels.
  457.  *****************************************************************************/
  458.  
  459.  
  460. #endif /* __CMSOUNDSYSTEM__ */
  461.